Add /generate-feature-docs skill for spec-to-docs generation#675
Add /generate-feature-docs skill for spec-to-docs generation#675
Conversation
Two-stage skill that converts implemented engineering specs into publisher-facing docs at docs/guide/, with handle verification against code, augment-in-place behavior for existing pages, and mechanical updates to configuration.md, api-reference.md, and error-reference.md. Establishes a spec-readiness convention (status frontmatter) and a directory split between drafts and implemented specs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sixteen tasks across three phases: prerequisites (VitePress exclusion, directory layout, spec migration, CLAUDE.md update), skill implementation (slash command + SKILL.md built up incrementally), and validation (greenfield, idempotency, augmentation, non-feature, and drift cases). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… SKILL Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds Section 16 documenting three amendments motivated by the JS Asset Auditor greenfield validation: verification-rate threshold (Section 16.1), branch-state heuristic (Section 16.2), and verified_against_commit audit field (Section 16.3). Section 6 updated to list the third optional field and to use chat-native prompt phrasing consistent with SKILL.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…SKILL - Edit 1: add optional frontmatter fields block (implemented_in, last_reviewed, verified_against_commit) to the spec readiness check section; specify that verified_against_commit is surfaced in the Stage 1 outline header - Edit 2: add Step 1.7a with verification-rate computation and a hard prompt when fewer than 50% of handles verify against the codebase - Edit 3: add Step 1.7b with a branch-state heuristic using git log from merge-base; surfaced as an informational note in the Stage 1 outline header - Step 1.9 outline template updated to include Verified against commit metadata and the conditional branch-state note Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mirrors the optional field added in design Section 16.3 and SKILL.md, so the documented schema stays in sync with what the skill recognizes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Auto-formatted by prettier --write to satisfy the docs/format CI check. Mechanical changes only: trailing whitespace, table column padding, blank lines around fenced code blocks, italic style normalized to underscores. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ChristianPavilonis
left a comment
ChristianPavilonis
left a comment
There was a problem hiding this comment.
Summary
This PR is directionally useful: the two-stage docs workflow, code-grounded extraction, spec lifecycle convention, and VitePress exclusion are all good additions. My main concern is that the skill reads too much like a policy document and uses many hard-negative rules. That will likely make the agent rigid and less collaborative. I recommend rewriting the skill around defaults, warnings, and ask-before behavior, reserving hard stops for destructive actions like pushing, committing without approval, or editing code when the task is docs-only.
| - One file under `docs/guide/<feature-slug>.md` (created or augmented). | ||
| - Up to three additive updates to `docs/guide/configuration.md`, `docs/guide/api-reference.md`, and `docs/guide/error-reference.md`. | ||
|
|
||
| Writes are confined to the four files listed above. You never write any other file, never open PRs, never push, never deploy, never modify code under `crates/`, and never modify the spec you are reading. |
There was a problem hiding this comment.
Output scope should be a default, not an absolute prohibition: This section uses hard boundary language: writes are confined to exactly four files and the agent never writes anything else. For a skill, I think this should be phrased as a default scope with ask-before behavior. Some docs work may legitimately need a sidebar, index, or related guide update.
Suggestion:
Default write scope is the generated feature page and relevant reference docs. If another docs file appears necessary, explain why and ask before editing it.| - Any other value, or missing `status`: stop. Print: | ||
| > "This spec has `status: <value>` (or no status). The skill operates on `status: implemented` specs. Continue without status: implemented? Reply `y` to proceed." | ||
|
|
||
| Wait for the user's reply. Treat any reply other than a single `y` (case-insensitive) as abort. On `y`, print this warning once before continuing: |
There was a problem hiding this comment.
Avoid exact-response gates for normal collaboration: Requiring a single literal y makes the skill feel brittle. This is useful for irreversible actions like committing, but too strict for proceeding with a draft.
Suggestion: Treat non-implemented status as a warning and continue on ordinary affirmative replies such as yes, proceed, continue, or draft it. Reserve exact confirmation for commits or destructive operations.
|
|
||
| If `verified_against_commit` is present, surface its value in the Stage 1 outline header (alongside the other metadata) so the user can compare it against the current branch state if drift is suspected. | ||
|
|
||
| ## Style rules (apply to ALL output, both chat messages and written files) |
There was a problem hiding this comment.
Style rules should apply to generated docs, not chat: Applying these rules to all chat messages is likely one reason the agent feels stiff. The agent should be able to collaborate naturally in chat while still producing docs that match the site style.
Suggestion:
Style rules apply to generated documentation files. In chat, be concise, clear, and collaborative.I would also remove the duplicate self-check section near the bottom of the skill.
| 1. Compute `verified_count` (handles marked `verified`) and `total_extracted_count` (all extracted handles, regardless of type). | ||
| 2. Compute `verification_rate = verified_count / total_extracted_count`. | ||
| 3. If `total_extracted_count` is zero, this is the "no shipped code" edge case (Section "Edge cases and failure modes"). Use the existing handling for that case. | ||
| 4. If `verification_rate < 0.50`, add a hard prompt to the Stage 1 "Issues" subsection: |
There was a problem hiding this comment.
The verification threshold should be a confidence warning, not a gate: A hard 50 percent verification threshold is likely to create false friction because handle extraction can be noisy. Specs may include examples, pseudocode, planned names, or docs-only concepts that do not grep cleanly.
Suggestion: Summarize handles as verified, unverified, and ambiguous. Ask how to treat unverified handles that would appear in final docs, but do not block generation solely based on a numeric threshold.
|
|
||
| Runs only after the user types `proceed`. Inputs: the spec, the approved outline from stage 1, and the existing docs. Output: files written to disk; nothing is committed until the user approves the diff. | ||
|
|
||
| ### Step 2.1: Branch check (before any writes) |
There was a problem hiding this comment.
Move branch and working-tree checks to commit time: Refusing to proceed before any writes makes the skill harder to use for drafting. Users often want to generate files, inspect the diff, and decide later. Branch hygiene matters most when committing.
Suggestion: Allow draft generation on any branch after user approval. Before committing, check the branch and working tree, stage only the generated docs files, and ask if a docs branch should be created.
|
|
||
| If any are present, rewrite. This includes prompts, status updates, summaries, the extraction outline, and the final diff-review message. | ||
|
|
||
| ## Out of scope |
There was a problem hiding this comment.
Prefer default boundaries over an out-of-scope list: This section is written entirely as negative constraints. In practice, those do not instructions can make the agent stubborn. I would reframe this as default boundaries and ask-before-expanding-scope guidance.
Suggestion:
## Default boundaries
This skill is optimized for publisher-facing docs. By default, focus on guide pages, reference docs, and code search for grounding concrete claims. If the user asks for adjacent work, such as updating narrative docs, changing specs, or preparing a PR, pause and confirm the expanded scope before doing it.2 participants
Summary
Adds a Claude Code skill that converts implemented engineering specs into publisher-facing documentation pages on the Trusted Server VitePress site. Closes a recurring gap where specs get written and code ships, but the docs at iabtechlab.github.io/trusted-server do not get updated.
The skill is invoked as
/generate-feature-docs <spec-path>and runs in two interactive stages: an extraction pass that produces a structured outline for user review, and a generation pass that writes prose, applies mechanical updates to reference docs, and commits on user approval. Built entirely on Claude Code's existing skill and slash-command primitives. No new runtime infrastructure.What's in this PR
.claude/skills/generate-feature-docs/SKILL.mdand slash command at.claude/commands/generate-feature-docs.md.docs/superpowers/specs/drafts/for brainstorm output,docs/superpowers/specs/implemented/for post-implementation truth, withstatus:frontmatter (draft,in-progress,implemented).drafts/withstatus: draft.srcExcludeforsuperpowers/**so internal specs no longer render on the public docs site.CLAUDE.md.docs/superpowers/specs/drafts/2026-04-28-generate-feature-docs-skill-design.mdand implementation plan atdocs/superpowers/plans/2026-04-28-generate-feature-docs-skill.md.What is NOT in this PR
srcExcludeconfig; the only runtime impact is on the public docs site (which removes internal spec pages, the desired outcome).Risk profile
Low. The skill is markdown-only, no compilation, no execution path through the runtime. The most material change is to the public docs site (internal specs no longer indexed). External links to those spec URLs will break, but they were never intended to be public.
Test plan
/generate-feature-docs docs/superpowers/specs/drafts/2026-04-28-generate-feature-docs-skill-design.mdto confirm the slash command is auto-discovered. Replyabortat the readiness prompt; expect a clean exit with no files written./superpowers/.cargo fmt,cargo clippy,vitest,npm run formatindocs/,npm run buildindocs/. Thecargo test --workspaceViceroy failure is pre-existing and unrelated to this branch.Follow-up issues
How to use the skill
After this lands, any team member who pulls
maincan invoke/generate-feature-docs <spec-path>against any spec underdocs/superpowers/specs/implemented/(withstatus: implementedfrontmatter) to generate or augment its publisher-facing guide page. The skill verifies handles (config keys, endpoints, headers, error variants) againstcrates/, surfaces drift before writing prose, and commits the result on user approval. See the design spec for the full behavior contract.